---
title: Checkbox
description: "Checkboxes allow users to select one or more items from a set and can turn an option on or off. Use checkboxes to: Select one or more options from a list, present a list containing sub-selections, or turn an item on or off in a desktop environment."
docType: Demo
docGroup: Components
group: Inputs
hooks: [useCheckboxGroup]
components: [Checkbox]
---

# Checkbox

[Checkboxes](https://m2.material.io/components/checkboxes#usage) allow users to
select one or more items from a set and can turn an option on or off. Use
checkboxes to:

- Select one or more options from a list
- Present a list containing sub-selections
- Turn an item on or off in a desktop environment

## Simple Checkbox

A checkbox can be created using the `Checkbox` component.

```demo source="./SimpleCheckbox.tsx"

```

### Icon After Label

The label can be placed before the checkbox icon by enabling the `iconAfter` prop.

```demo source="./IconAfterLabel.tsx"

```

### Stacked Checkbox

The label can be stacked above or below the checkbox by enabling the `stacked` prop.

```demo source="./StackedCheckbox.tsx"

```

## Checkbox Sizes

The `Checkbox` has multiple sizes: `normal` (default), `small`, `dense`,
and `large`. The size can also be set to `auto` which will update the checkbox
to match the current font size.

```demo source="./CheckboxSizes.tsx"

```

## Checkbox States

The `Checkbox` also has different states that can be applied. The most common
will be the `error` or `disabled` states but also supports `active`.

```demo source="./CheckboxStates.tsx"

```

## Controlling Checkboxes

The `Checkbox` can be controlled by providing the `checked` prop and `onChange`
like a native `<input type="checkbox">`:

```demo source="./ControllingCheckboxes.tsx"

```

## Indeterminate Checkboxes

[Indeterminate checkboxes](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/checkbox#indeterminate_state_checkboxes) are
when there is a third state where it's impossible to say whether the item is
toggled on or off. The most common occupance is when there is a group of
checkboxes where one checkbox can toggle all of them on or off.

To create an indeterminate checkbox, enable the `indeterminate` prop and the
indeterminate icon will display while checked.

```demo source="./IndeterminateCheckbox.tsx"

```

### useCheckboxGroup Hook

`react-md` provides a hook: `useCheckboxGroup` that can be used to handle the
state of a checkbox group with or without an indeterminate checkbox. The hook
requires a `name` to be provided and an optional list of `defaultCheckedValues`
returning an object containing:

- `getCheckboxProps` - A function to generate the props for a checkbox based on
  the checkbox's value.
- `checkedValues` - A `ReadonlySet` of the current checked values in the group.
- `setCheckedValues` - A `UseStateSetter` to manually control the
  `checkedValues` state if needed.
- `reset` - Resets the state to the `defaultCheckedValues` (an empty list by
  default).

> !Info! The `checkedValues` and `getCheckboxProps` will be strictly typed for Typescript users.
> The type will be derived from the `defaultCheckedValues` if provided,
> otherwise a [type parameter](https://www.typescriptlang.org/docs/handbook/2/generics.html)
> can provided to set the type.

```demo source="./CheckboxGroupHook.tsx"

```

## Custom Icons

The `Checkbox` component will use the
[checkbox](/customization/icon-config#checkbox),
[checkboxChecked](/customization/icon-config#checkboxChecked), and
[checkboxIndeterminate](/customization/icon-config#checkboxIndeterminate) icons
from the `ICON_CONFIG` by default.

```demo source="./CustomIcons.tsx"

```

## Checkbox with Messages

The `Checkbox` component is wrapped in the
[FormMessageContainer](/components/form-message#form-message-container) so additional
hint or error messages can be displayed.

```demo source="./CheckboxWithMessages.tsx"

```
